home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / src / exampleCode / opengl / oat / README < prev    next >
Encoding:
Text File  |  1994-08-02  |  7.0 KB  |  192 lines
  1.  
  2.              ~4Dgifts/toolbox/src/exampleCode/opengl/oat README
  3.  
  4.  
  5.                            OpenGL Attribute Tester
  6.                            =======================
  7.  
  8.  
  9. 'oat' (OpenGL Attribute Tester) is a program for testing the functionality
  10. of OpenGL on different platforms.
  11.  
  12. It provides a GUI interface to test most (hopefully all) the different
  13. attributes that are changeable in OpenGL.
  14.  
  15. run it as:
  16.  
  17. oat [<filemame>]
  18.  
  19. where <filename> is an Inventor .iv data file.  In the iv subdir you'll 
  20. find some test files, like cone.iv, sphere.iv, tri.iv (triangle), 
  21. plane.iv (a quad), etc.
  22.  
  23. Also, the /usr/demos/data/yaodl/*.ydl files have been converted into .iv 
  24. format and you can find them in 
  25. /hosts/mistral.esd/usr/people/kyriazis/oat/bin/iv, if you are internal to SGI.
  26.  
  27. This program uses the Inventor interaction paradigm, so if you are
  28. unfamiliar with it, go learn it! :-)  Actually, play around with ivview
  29. to get accustomed to it.
  30.  
  31. This program is not meant to be an Inventor file viewer, but a tester for
  32. OpenGL attributes, etc., so all attributes that your .iv file contains
  33. are being stripped out, hopefully in a graceful manner.  Also, some Inventor
  34. primitives are not supported, because I had to alter them to get rid of
  35. any interaction that Inventor has with OpenGL.  Namely, the only primitives
  36. that are supported are: Cone, Cylinder, Sphere, Cube, FaceSet and 
  37. IndexedFaceSet.
  38.  
  39. In addition, when oat starts up it uses the initial OpenGL defaults, which
  40. are not necesserily visually pleasing:  No lighting, no shading, everything
  41. is a dull white.  But, again, oat is supposed to test OpenGL, so it starts
  42. up by setting no OpenGL attributes whatsoever.
  43.  
  44.  
  45. Command-Line Options
  46. --------------------
  47.  
  48. They go before the filename.  Current ones are:
  49.  
  50. -ci    Start up in a Color Index visual.
  51.  
  52. -sb    Start up in a single-buffer mode (instead of double buffer if
  53.     that exists).
  54.  
  55. -nr    Disable quick interaction.  By default, everything you change
  56.     (through the GUI) triggers a redraw.  This frag disables this
  57.     behavior, so you can change multiple parameters at the same time,
  58.     and then redraw the scene manually.
  59.  
  60. -fps    Print (to stdout) frames per second after each frame.  It is
  61.     calculated as 1 / seconds-per-frame.
  62.  
  63. -h    Displays a help screen.
  64.  
  65.  
  66. User Interface:
  67. ---------------
  68.  
  69. There are several menus and popup panels that are available.  We will go
  70. through them as they appear in the menubar.
  71.  
  72. FILE:
  73.   Open:        Open an .iv file
  74.   Quit:        Quit oat
  75.  
  76. Manips:        Selects an Inventor SoTransformManip to be used when
  77.         using the pointer (from the panel on the right).
  78.     
  79. POPUPS:        These are the popup panels that allow you to alter OpenGL
  80.         attribute.  Classification was done more-or-less according
  81.         to "The OpenGL Machine" poster.
  82.  
  83. VIEW:        Setup ortho or perspective view.
  84.  
  85. VISUALS:    Choose an X visual to be used..  The menu contains a list of
  86.         all the visuals of the X server that support OpenGL rendering,
  87.         in order words, all the visuals that that you can use in
  88.         the current graphics hardware.
  89.  
  90.  
  91. One thing which is a bit non-obvious is that for one-line text item, you
  92. let the program know you are done by pressing your average Return key.
  93. For multi-line text items, you use the ENTER key at the far right of the
  94. keyboard..  (It was a Motif-ism...  If you find an easy way to solve this
  95. problem, change TextItem.* and MatrixItem.*).
  96.  
  97. There is also a column of buttons on the right of the drawing area.
  98. These buttons are almost identical to the buttons existing in SceneViewer.
  99. Here is a brief description:
  100.  
  101. Arrow/Hand:    Pick/Move toggles.
  102.  
  103. House:        Go Home
  104.  
  105. House w/ arrow:    Set Home position.
  106.  
  107. Weird eye:    Alter the view so that the BBox of the scene fits in view.
  108.  
  109. Target:        Smooth motion to picked point.
  110.  
  111. PIXMAP:        Create a pixmap using current visual, draw in it, dump it in
  112.         an RGB file, and then display that file using ipaste.
  113.  
  114.  
  115. IMPLEMENTATION:
  116.  
  117. This program was written using C++, Inventor, and ViewKit.  I attempted
  118. to structure code as much as possible, so it should be relatively easy
  119. to alter or add functionality.  Look at src/Makefile for a brief
  120. classification of the files.
  121.  
  122. GlWindow is the main "dispatcher" class that figures out what to do with
  123. each user event.  Unfortunately, it's a pretty monilithic class, and I
  124. haven't bothered myself with finding an easy way of splitting it up. If
  125. you find an easy way, please let me know.
  126.  
  127. There is one class for each of the user-interface panels that show up.
  128. The user interface is created automatically in an algorithmic manner.  That's
  129. why the layout my look a bit stupid.  The superclass (IfaceGenerator) of
  130. the interface classes provides the parser that reads in the description
  131. of the window and creates the Motif widgets.  There is a wrapper around
  132. each one of the OpenGL functions in order to provide an easy way to 
  133. provide feedback debugging information.  Additionally, each user interface
  134. class has a local mirror of the part of the OpenGL state that it alters, so
  135. that it can keep OpenGL in sync with the user interface when visuals are
  136. changed, etc.
  137.  
  138. Inventor is used for primitive description and database traversal.  Since
  139. Inventor does a lot of attribute binding behind our backs, I copied the
  140. most significant parts of the GLRender routines of certain SoShapes and
  141. made local copies of those primitives that do not alter the state.  In this
  142. way, Oat has full control of the OpenGL state.  Instances of the those
  143. local classes are created when an Inventor file is read in.  After an
  144. Inventor file is being loaded in, it is being traversed to check if it
  145. contains any shape nodes that are not "converted", or any attribute nodes.
  146. Such nodes are then erased from the tree.
  147.  
  148. This program uses X application default files.  By default "make install"
  149. put the defaults file (called Oat) into $ROOT/usr/lib/X11/app-defaults.
  150. You should make arrangements of being able to have that directory in your 
  151. XAPPLRESDIR or XUSERFILESEARCHPATH, otherwise your user interface may
  152. pop up in that ugly default Motif blue color with the very ugly buttons.
  153.  
  154.  
  155.  
  156. Also, for your convenience, the parent directory has a file called
  157. "stipple-pats".  This contains sample stipple patterns to be used with
  158. the polygon stipple text item.  In order to use one of them, empty out
  159. the polygon stipple text area, 'cat' the stipple-pats file in a separate
  160. window, highlight the pattern you want (with the left mouse button), and
  161. paste it in the stipple text area (with the middle button).  Don't forget
  162. to confirm your selection with ENTER (not Return;  this is a multi-line
  163. text item).
  164.  
  165.  
  166.  
  167. USER-DEFINED PRIMITIVES:
  168.  
  169. I have made a subclass of Inventor's SoShape node, which allows the person
  170. who plays around with 'oat', to add his own OpenGL code in the GlUserDef1
  171. class and test some obscure OpenGL case, that way.
  172.  
  173. You can make a .iv file that contains an instance of UserDef1, and load the
  174. file as you would normally.
  175.  
  176. If you'd like to play around with that file, look in GlUserDef1.* for code
  177. that has been #ifdef'ed out like:
  178.  
  179. #ifdef FILL_HERE
  180. ..
  181. ..
  182. #endif
  183.  
  184. It should be more or less obvious...
  185.  
  186.  
  187.  
  188. If you have any questions, please send mail to kyriazis@sgi.com
  189.  
  190. George Kyriazis
  191. kyriazis@sgi.com
  192.